Fetch Company and LLP Master Data API - v2

This document highlights details of the Company and LLP Master Data API - v2.

API Description

Objective

The Fetch Company and LLP Master Data API - v2 authenticates the Company Identity Number(CIN), Limited Liability Partnership Identification Number(LLPIN), Foreign Company Registration Number(FCRN) and Foreign Limited Liability Partnership Identification Numbers (FLLPIN) issued by the Ministry of Corporate Affairs (MCA) and retrieves the master data associated with it.

Input	Output
The unique CIN, LLPIN, FCRN or FLLPIN	The master data of the company or the Limited Liability Partnership(LLP) associated with the identity number

API URL

https://ind-engine.thomas.hyperverge.co/v1/fetchCINDetailsV2

API Endpoint

fetchCINDetailsV2

Overview

The Fetch Company and LLP Master Data API - v2 is RESTful and uses standard HTTP verbs and status codes. The responses are in JSON format and you should send all data in JSON format through a POST request.

Authentication

You need a unique pair of application ID ( appId ) and application key (appKey) from HyperVerge to verify your identity for accessing the API.

Parameter	Mandatory or Optional	Description	Allowed Values
content-type	Mandatory	This parameter defines the media type for the request payload	application/json
appId	Mandatory	The application identifier shared by HyperVerge. You can find the details in the dashboard's credentials tab.	This should be a unique value.
appKey	Mandatory	The application key shared by HyperVerge. You can find the details in the dashboard's credentials tab.	This should be a unique value.
transactionId	Mandatory	A unique identifier for tracking a user journey	This should be both unique and easily associated with the user's journey in your application(s)

Inputs

The following table provides the details of the parameters required for the API's request body:

Parameter	Mandatory or Optional	Description
id	Mandatory	CIN/LLPIN/FCRN/FLLPIN
consent	Mandatory	Consent flag indicating user permission (Y/N)

Request

The following code snippet demonstrates a standard curl request for the API:

curl --location 'https://ind-engine.thomas.hyperverge.co/v1/fetchCINDetailsV2' \
--header 'Content-Type: application/json' \
--header 'appId: <Enter_the_HyperVerge_appId>' \
--header 'appKey: <Enter_the_HyperVerge_appKey>' \
--header 'transactionId: <Enter_the_HyperVerge_transactionID>' \
--data '{
         "id":"<Enter_the_unique_ID>",
         "consent":"<Enter_Y_or_N>"
       }'

Success Response

The following code snippet demonstrates a success response from the API:

{
    "status": "success",
    "statusCode": "200",
    "result": {
        "code": 200,
        "data": {
            "company_master_data": {
                "company_category": "<Company_Category>",
                "email_id": "<Email_ID>",
                "class_of_company": "<Class_Of_Company>",
                "date_of_last_agm": "<Date_Of_Last_AGM>",
                "registered_address": "<Registered_Address>",
                "registration_number": "<Registration_Number>",
                "paid_up_capital(rs)": "<Paid_Up_Capital>",
                "whether_listed_or_not": "<Whether_Listed_Or_Not>",
                "cin": "<CIN>",
                "company_subcategory": "<Company_Subcategory>",
                "authorised_capital(rs)": "<Authorised_Capital>",
                "company_status(for_efiling)": "<Company_Status>",
                "roc_code": "<ROC_Code>",
                "date_of_balance_sheet": "<Date_Of_Balance_Sheet>",
                "date_of_incorporation": "<Date_Of_Incorporation>",
                "company_name": "<Company_Name>",
                "active_compliance": "<Active_Compliance>",
                "rd_region": "<RD_Region>",
                "total_director": <Total_Director>
            },
            "charges": [
                {
                    "date_of_creation": "<Date_Of_Creation>",
                    "date_of_modification": "<Date_Of_Modification>",
                    "charge_amount": "<Charge_Amount>",
                    "status": "<Status>"
                }
            ],
            "directors/signatory_details": [
                {
                    "end_date": "<End_Date>",
                    "din/pan": "<DIN_PAN>",
                    "designation": "<Designation>",
                    "begin_date": "<Begin_Date>",
                    "name": "<Name>"
                }
            ]
        }
    },
    "metaData": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

Success Response Details

The following table outlines the details of the success response from the API:

Parameter	Type	Description
status	string	The status of the API response
statusCode	string	The HTTP status code of the response
result	object	The main result object containing all response data
code	integer	The internal code representing the operation result
data	object	The data object containing company master data and related information
company_master_data	object	The master data of the company or LLP
result.data.company_master_data.company_category	string	The category of the company (e.g., "Company limited by shares")
result.data.company_master_data.email_id	string	The company's registered email ID
result.data.company_master_data.class_of_company	string	The class of company (e.g., "Public")
result.data.company_master_data.date_of_last_agm	string	The date of the last Annual General Meeting
result.data.company_master_data.registered_address	string	The full registered address of the company
result.data.company_master_data.registration_number	string	The company registration number
result.data.company_master_data.paid_up_capital(rs)	string	The paid-up capital in INR
result.data.company_master_data.whether_listed_or_not	string	The information about whether the company is listed or not
result.data.company_master_data.cin	string	The Corporate Identification Number
result.data.company_master_data.company_subcategory	string	The subcategory of the company
result.data.company_master_data.authorised_capital(rs)	string	The authorised capital in INR
result.data.company_master_data.company_status(for_efiling)	string	The current filing status (e.g., "Active")
result.data.company_master_data.roc_code	string	The Registrar of Companies code
result.data.company_master_data.date_of_balance_sheet	string	The date of the last balance sheet filed
result.data.company_master_data.date_of_incorporation	string	The incorporation date
result.data.company_master_data.company_name	string	The registered company name
result.data.company_master_data.active_compliance	string	The compliance status
result.data.company_master_data.rd_region	string	The Regional Directorate
result.data.company_master_data.total_director	number	The total number of directors
result.data.charges	array	The list of charges associated with the company
result.data.charges[].date_of_creation	string	The date the charge was created
result.data.charges[].date_of_modification	string	The date of modification (if any)
result.data.charges[].charge_amount	string	The amount of charge in INR
result.data.charges[].status	string	The status of the charge (e.g., "OPEN", "CLOSED")
result.data.directors/signatory_details	array	The list of directors and signatory details
result.data.directors/signatory_details[].end_date	string	The end date of the director/signatory's tenure
result.data.directors/signatory_details[].din/pan	string	The Director Identification Number (DIN) or PAN
result.data.directors/signatory_details[].designation	string	The designation (if provided)
result.data.directors/signatory_details[].begin_date	string	The start date of the director/signatory's tenure
result.data.directors/signatory_details[].name	string	The full name of the director/signatory
metaData	object	The metadata object containing request tracking information
metaData.requestId	string	The unique identifier for the request
metaData.transactionId	string	The unique identifier for the transaction

Failure Response

The following is a failure response from the Fetch Company and LLP Master Data API - v2:

{
    "status": "failure",
    "statusCode": "422",
    "error": {
        "message": "Entered CIN/LLPIN/FLLPIN/FCRN is not found. Please enter valid details.",
        "timestamp": <Timestamp>
    },
    "metaData": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

Error Responses

The following are some error responses from the Fetch Company and LLP Master Data API - v2:

ID Missing

{
    "status": "failure",
    "statusCode": "400",
    "error": "id is required",
    "metaData": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

Consent Missing

{
    "status": "failure",
    "statusCode": "400",
    "error": "consent is required",
    "metaData": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

Invalid Consent

{
    "status": "failure",
    "statusCode": "400",
    "error": {
        "message": "Invalid parameter: Consent is required.",
        "timestamp": <Timestamp>
    },
    "metaData": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

Invalid CIN/LLPIN/FLLPIN/FCRN

{
    "status": "failure",
    "statusCode": "400",
    "error": {
        "message": "Invalid CIN/LLPIN/FLLPIN/FCRN entered. Please enter valid details.",
        "timestamp": <Timestamp>
    },
    "metaData": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

Missing/Invalid Credentials

{
    "message": "Missing/Invalid credentials",
    "statusCode": 401,
    "status": "failure"
}

Error Response Details

A failure or error response from the module contains a failure status, with a relevant status code and error message.

The following table lists all error responses:

Status Code	Error Message	Error Description
400	id is required	This error occurs when the id parameter is not provided in the request.
400	consent is required	This error occurs when the consent parameter is not provided in the request.
400	Invalid CIN/LLPIN/FLLPIN/FCRN entered. Please enter valid details	This error occurs when an invalid CIN/LLPIN/FLLPIN/FCRN is provided.
400	Invalid parameter: Consent is required.	This error occurs when user consent is not provided in the request parameters.
401	Missing/Invalid credentials	This error occurs when the appId or appKey is missing or incorrect in the request headers.
422	Entered CIN/LLPIN/FLLPIN/FCRN is not found. Please enter valid details	This error occurs when the provided CIN/LLPIN/FLLPIN/FCRN does not exist in the records.
500	Internal Server Error	This error occurs due to an unexpected server-side failure. Please contact HV for investigation.
503	External source downtime	This error occurs when the external source is unavailable or temporarily down.